home *** CD-ROM | disk | FTP | other *** search
/ MacWorld Ultimate Mac / Macworld Ultimate Mac CD-ROM (1994)(IDG).iso / The Best of BMUG / Utilities / Control Panels and Extensions / ClipboardMagician.76 / About Clipboard Magician 0.76 < prev    next >
Text File  |  1994-04-23  |  24KB  |  106 lines
  1. Clipboard Magician 0.76                                1993-6-24
  2.                                                         by Ed Lai
  3. • not an Apple Computer, Inc. product •     lai@apple.com, AppleLink: Lai1
  4. -----------------------------------------------------------------
  5. •••  dedicated to all those, who fight for democracy in China and Hong Kong •••
  6. -----------------------------------------------------------------
  7.  
  8. There is a slight variation between the Get Clipboard Apple Event used in Clipboard Magician and AppleScript. Version 0.76 converts over so that the command is the same and you would be able to get it from other scriptable application that supports getting the keyboard. Jim Walker updated by picture cropping CNVT and contributed another one that converts isolated carriage return to space.
  9.  
  10. -----------------------------------------------------------------------
  11.  
  12. About Clipboard Magician version 0.75
  13.  
  14. Version 0.75 supports the final version of AppleScript. The support of scpt in version 0.72 is for beta OSA, it can no longer be used because of changes in the final OSA. There are now also added support for OSA scripting. A 'scpt' resource can be edited and executed or decompiled into text. Text can be compiled into scpt resource or executed as an OSA script. Of course that depends on the OSA component used. You may hold down the option key to select the default OSA component for Clipboard Magician for these last two operations. Note that after you have compile an OSA script into a scpt resource, you may save it into the Magic Wand and then it can be used as a single operation in future.
  15.  
  16. The support of OSA from Clipboard Magician is an important milestone in Clipboard Magican since now OSA provides a scripting language for Clipboard Magician. The first version of Clipboard Magician version is 0.5 because it is half baked. This version is 0.75 because we have marched half way toward the final goal in this version. The next few versions will improve the integeration of scripting into Clipboard Magician.
  17.  
  18. There are other minor changes. When you are creating an Apple Event you may now specify the signature of the application. There are bug fixes in template editing. For the Chinese users, zW encoding/decoding now has been upgraded to use the HGB code used since system 6 of the Chinese system.
  19.  
  20. There are problem when the FKEYs are used to launch Clipboard Magician. The problem will require a redesign and it has not been fixed yet.
  21.  
  22. -----------------------------------------------------------------------
  23.  
  24. About Clipboard Magician version 0.72
  25.  
  26. Version 0.72 only contains minor bug fix. If a data type only has a few usable commands, garbage may show up after the last commands this has been fixed.
  27.  
  28. We have added a new CNVT which crop a Bitmap and is contributed by James W. Walker. 
  29.  
  30. For the system 7 only CNVT. One of the most useful CNVT for me is the one that get the clipboard of a remote machine. There was a bug that has the effect that it ends up hard coding to my other machine, so it is useless for everybody else. This is now fixed.
  31.  
  32. The really significant of version 0.72 is the addition of the support for 'scpt' resource, the OSA scripting languages resource. Since you need an OSA scripting component for it to work, very few of you will be able to use it, but it will be coming. All these time Clipboard Magician needs a scripting language to tie the CNVT functions together. I do not want to write a scripting language myself, and 'CNV@' can be only be considered a very primitive way of stringing CNVT together. With support of 'scpt' resource, it is now possible to use use any of the future Macintosh scripting language conforming to the OSA architecture. In 0.72 we have added CNVT to display and execute a 'scpt' script. CNVT to compile a 'scpt' script will be added in future. In the mean time you have to generate 'scpt' resource using other scripting developing environment.
  33.   
  34. -----------------------------------------------------------------------
  35.  
  36. About Clipboard Magician version 0.71
  37.  
  38. We are reaching the 32K limit of teach text. So we start a new file to describe what is new in version 0.70. Please refer to the file About Clipboard Magician for other basic information on how to use Clipboard Magician.
  39.  
  40. Version 0.70 allows Clipboard Magician to be used as an Apple Event server, very few people can take advantage of that because there are very few Apple Event client applications. Version 0.71 will introduce more function where Clipboard Magician acts as an Apple Event client, mostly by adding new CNVTs. Now more people can now actually uses Apple Event, if only to let one Clipboard Magician to talk to another one in a remote machine.
  41.  
  42. To be an Apple Event client, you must establish another application (usually another copy of Clipboard Magician on another machine) as the target server. There is a CNVT to get the default target. You may change the default target by invoking the CNVT with the option key down. The first operation you can is to talk to the remote Clipboard Magician and read the clipboard from the other machine. The event sent is really a core event which means that in future it would work with other applications, but for now only Clipboard Magician 0.71 on the other machine would respond. Also in system 7.0, the background application cannot get the clipboard of the front application, so unless Clipboard Magician is the front application, you would not get the most current clipboard.
  43.  
  44. And whenever you execute a Clipboard Magician CNVT command, if you hold down the control key, the command will be sent over to the default target and be executed over there. So for example if you do a "Get Gestalt", you get the Gestalt in your own machine. If you hold down the control key, you will be getting the Gestalt of the remote machine (provided Clipboard Magician 0.71 is already running on the other machine and there is a "Get Gestalt" CNVT on that copy of Clipboard Magician). Control key will be replaced by command key in future, but for now we cannot do it because the command key is used.
  45.  
  46. You may also send any Apple Event from Clipboard Magician using your clipboard data as the direct parameter in the Apple Event. There is a new CNVT that let you make a simple Apple Event. With this CNVT, you specify the event class and event id, and either the target ID or the target application signature and create an externalized form of Apple Event "$ae$". You may then incorporate it into Clipboard Magician by using the "Save To Magic Wand" command. From then on, it can act as any other command except that it is sending an Apple Event to another application.
  47.  
  48. As far as Clipboard Magician is concerned, there is nothing special about the data type "$ae$". It is just another data type like "XCMD" that it can executed only because there is the right CNVT to execute it. There is nothing special about the CNVT in the Magic Wand to make the "$ae$" data either. It is just a bare bone builder for a bare bone event. If you can find another application that let you build up an Apple Event and externalized it as "$ae$", you can also use that "$ae$" as well. And that is the way to go if you want to use a more complex Apple Event.
  49.  
  50. As an example of $ae$, we build one that send the evaluate command to HyperCard (HyperCard must be already running in the same machine and version 2.1 or above). This allows you to have any HyperTalk expression and evaluate it. Of course this may not be very useful since it is not too difficult to just switch over to HyperCard and use the message box.
  51.  
  52. The evaluate HyperTalk expression will be more useful if it can be done from any application. If you can do it from your word processor then your word processor document becomes a HyperCard message box. In previous version of Clipboard Magician there is a way where you can execute Clipboard Magician commands from any application using low level event. It was very restrictive, klugy and difficult to use. Worst yet there is a bug and it may crash your application. With 0.71 the bug is fixed. Furthermore with system 7 there are easier way to do it. The old mechanism is still there because it words with system 6, but it is likely to be removed in the next version.
  53.  
  54. With the new mechanism, Clipboard Magician must already be running. This is the opposite of the old mechanism. If both the application and Clipboard Magician are Apple Event aware (this means that Clipboard Magician must be an application and not a DA), then they would communicate by Apple Event. Otherwise low level events posting is used. There is advantage in the first method because there will be no unnecessary layer switch. When the FKEY and Clipboard Magician communicate by Apple Event, the result is still put back into the clipboard and is paste back by posting the command-v. However, if the application reads from the private scrap and not the public scrap, then it still fails. This is not a problem when low level event posting is used because it always resulted in a layer switch. So if your application has the problem that it would paste back the result, you can hold down the control key with your FKEY. This would force the FKEY to use the low level event approach and paste the result back.
  55.  
  56. In version 0.70 or earlier, the automatic execution will repeat the last operation. However, this is not a good idea if Clipboard Magician is already running  as required by the new mechanism. This means that you are likely to be using Clipboard Magician directly. The last operation will keep changing so it is difficult to remember what operation will be triggered by the FKEY. With version 0.71, there is a new menu item to let you choose which operation to be executed automatically so the operation will always be the same.
  57.  
  58. Just about every problem reported with version 0.70 is related to the fact that people do not read manual and does not realize that to run Clipboard Magician as an application, it is necessary to copy the resource from the DA to the application. In this version, a warning will be given when that happens.
  59.  
  60. Undoubtedly you can see that Clipboard Magician has a new look and a complete set of icons. This has been designed by Morgan Davis, Thanks.
  61.  
  62. Most of the new feature in version 0.70 and 0.71 requires system 7. So usually there is no good reason to use version 0.7x in system 6. However there is a new feature that is useful even in system 6. There are a number of requests that I should be using font size 9 to show more commands. However, I stay with font size 12 because Chinese character needs that size. In this version, you can change a resource to change the font (this also affects other dialog), font size and font style. In resource OPTS -16000, offset 10 is the font id, offset 12 if the font style and offset 14 is the font size. So now everyone can be happy.
  63.  
  64. In version 0.70, running Clipboard Magician as an application can cause memory location 0 be written over. This bug is fixed in version 0.71. In previous versions, I do not check if the Clipboard Magician window position can be visible on the screen. This bug has been fixed in this version.
  65.  
  66. One of the main reason that Magic Wand is in the system folder (or the preference folder of the system folder in system 7) is that as a DA, there is no natural place to put it. However, if it is an application, then a reasonable place is to put Magic Wand in the same folder as the application. In version 0.71, we would look for Magic Wand first in the same folder. If it is not in the same folder, we look for it in the system folder.
  67.  
  68. -----------------------------------------------------------------------
  69.  
  70. About Clipboard Magician version 0.70
  71.  
  72. There is a bug in Magic Wand Utility from version 0.65. When you copy CNVT to replace old one, it is possible to get duplicate resources. The bug is now fixed in the utility. The Magic Wand file distributed in 0.65 was corrupted because of this. You may want to repair it with ResEdit if you want to keep using the old Magic Wand file.
  73.  
  74. Clipboard Magician version 0.70 is the first release with 7.0 system feature. If you are using system 6, you probably don't need to use this new version. The only reason you may use version 0.70 in system 6 is that it is possible to run Clipboard Magician as an application rather than a DA. If you do not want to install a DA into your system, then you may want to use 0.70 as an application, but you will lose the ability to launch it with FKEY 5 and FKEY 6 in system 6.
  75.  
  76. If you are running system 7 but want to continue using Clipboard Magician as a DA, then again there is no need to use version 0.70. 0.65 will run just as well as 0.70, you only need to use the latest FKEY 6 as the old FKEY 6 does not work in system 7. The only advantage of using version 0.70 as a DA in system 7 is that the Magic Wand file is in the preference folder so it would not cluster up your system folder.
  77.  
  78. One thing that is different under system 7 is that if you have Clipboard Magician at the background, and you foreground application cut something into the public clipboard, the content will not be visiable in Clipboard Magician until it comes to the foreground. This behaviour is from system 7 and not under my control. In my opinion, this is a system 7 bug.
  79.  
  80. People has various reasons why they prefer using an application rather than a DA. In the case of Clipboard Magician 0.70, there is a special reason. In system 7.0, only an application with certain size resource bit set can send and receive Apple Events. Clipboard Magician 0.70 can be used as an Apple Event server where the various CNVTs will be Apple Event handlers. That is the main reason why it need to be an application. If you do not have any application that can send arbitrary Apple Event, you do not need to use Clipboard Magician as an Apple Event server and hence you do not need version 0.70. However, with the right XCMD or MPW tools, HyperCard and MPW Shell can send Apple Event, and so can QuickKey. So Apple Event client application is more prevalent than you may think.
  81.  
  82. There is in fact very little code change from version 0.65 to 0.70. There is a minimum amount of changes to accommodate Apple Events and more changes will be incorporated in future. Nonetheless the changes are significant. It represents an important step to achieve the goal of Clipboard Magician. It points to the future direction of Clipboard Magician. In this sense version 0.70 represents the most important new version of Clipboard Magician.
  83.  
  84. All of the following discussion involves Apple Event. A good knowledge of using Apple Event is assumed. If you are not familiar with Apple Event, you should wait until you read up on Apple Event. If you are not interested in using Apple Event, you can skip everything until you get to the last paragraph. The last paragraph will discuss some feature that will make use of Apple Event but will require no knowledge of Apple Event.
  85.  
  86. To take advantage of Apple Event you must run Clipboard Magician as an application, and it is easier to write an application than a DA. However I do not wish to rewrite it as an application yet. People who may benefit most from Clipboard Magician are those who run UniFinder in a 1M machine. So I intend to keep it as a DA for a while. As I mentioned earlier, the code change is a minimum. To turn it into an application I shall use a shell application to run the DA. This shell is designed for Clipboard Magician and may not work for other DA. The Clipboard Magician DA for historical reason is stored in a file called AlChemist. The Clipboard Magician application you got in this release is no more than an empty shell. To use it you have to copy all the resources from the AlChemist into the application. If you want to keep using FKEY 5 and 6, you need to put your application or its alias into the Apple Menu folder.
  87.  
  88. Now your application can receive Apple Event, but what Apple Events can it respond to? If you select a command and do About This Operation menu command from Clipboard Magician, you are usually given an eight character ID for the command. People who has been programming with Clipboard Magician have been using these ID for calling other CNVT without worrying about the name of the other CNVT being localized. If the eight byte character is missing, you can always add them yourself as part of the CNV! resource (I do not have time to assign ID to a lot of the CNVT yet). These ID will be used as the event class and event ID for the Apple Event handler. The direct parameter of the Apple Event will be the data you want to operate on, and the result is return as the direct parameter of the reply.
  89.  
  90. None of the CNVT has been rewritten for the purpose of Apple Event. However Apple Event demands certain behavior from its handlers. For example, a server may ask a server to do something in a remote machine without any user interaction. However a lot of the CNVTs pop up dialog box for user interaction. To get around the problem until the time when all the CNVTs have been rewritten, the shell patches the SF calls, GetNewDialog etc so that if no interaction is allowed, SF will return reply.good = false and GetNewDialog will return nil. So if the CNVT has been written to check whether GetNewDialog returns nil before proceeding, then the CNVT would function correctly as an Apple Event handler when no interaction is allowed. Of course if the CNVT does not check that then it is going to crash. Most of the CNVT I wrote should be OK but I have not checked them individually.
  91.  
  92. The shell has also been written so that kAEAlwaysInteract would translate into option key down in Clipboard Magician so that you will be able to modify the default options. There are two options for the shell that you can modify using ResEdit. The resource is 'SOPT' and the ResEdit template comes with the Shell. The first option is to force the shell to use the system heap. The second option is related to Apple Events. When Clipboard Magician is used a server, you may specified whether you allow any interaction when an Apple Event comes from another application or another machine.
  93.  
  94. In order for the CNVT to act like it was really designed for Apple Event, it should have accept more parameters. Suppose you want to save some data into a file, the "Save to data fork" CNVT may be a good CNVT to use. However, the current CNVT uses SF to ask for the file name. When used as an Apple Event handler, you need to be able to specify the file name as a parameter without SF, otherwise it would be useless in a scripting language. Here we can see the future direction of the CNVT. They can be used for programming in a scripting language when you can specify all the parameters. When no parameter is specified, the CNVT can still be used as a GUI to interact with the user to let the user specify what he want. This dual nature of CNVT has always been a design goal of Clipboard Magician. The CNV@ resource can be viewed as a poor scripting language with recording built in. The future direction will be the completion of the goal by integration of Clipboard Magician to other scripting language.
  95.  
  96. The question is then whether we can achieve some of that goal now, in version 0.70 and before CNVTs are being rewritten. Again we shall try to do these by patching some toolbox calls. Whenever a SF calls is made, the patch would look to see if this is from an Apple Event and then would try to get an alias from the keyword parameter of 'SFIN' or 'SFOU' ("SFIN' for SFGet and 'SFOU' for SFPut). If there is such a parameter, it is returned as the result of the SF call. So it is possible to specify the destination file in the "Save to data fork" CNVT. There is also way to specify parameters in modal dialog/alert. The parameter with the keyword 'JRNL' is a list. The list item is usually a numeric value. The number is the item number of a dialog/alert to be hit and will be returned as the result of ModalDialog. If a number value is followed by a list item of the type TEXT, then the text string will be entered into the item of the dialog.
  97.  
  98. In this way it is possible to program some of the user interaction in a CNVT through Apple Event parameters. Of course it is hardly perfect and there are many case where it is not possible to fully program the interaction. In other case, while it is possible to fully program the interaction, the very fact that no interaction is allowed will prevent this being performed. This is a stop gap solution until the CNVT are being rewritten.
  99.  
  100. Ideally a lot of detail of Apple Event would be hidden by the client application. There is a resource 'aete' defining how Apple Event parameters should look like. If the client application can make use of the 'aete' resource, then you need not worry about the details of the parameter. However there are some problems in defining 'aete' resource for Clipboard Magicain. People may have customerized their Magic Wand file so it is not possible to have a fixed 'aete' resource. As a temporary solution we include a new CNVT that would make an 'aete' resource out of your Magic Wand file. Then you can generate you own 'aete' resource for your Clipboard Magician server. However, the format of 'aete' resource is now in beta and not yet finalized, so this may not work in future. Also it would not take account of the extra parameters such as the 'SFIN' 'SFOU' mentioned earlier. We shall try a more elaborate solution in future.
  101.  
  102. The make aete CNVT, as well as a Make Alias CNVT and a AECoerce CNVT are all system 7 specific CNVT. They are put into a different file "System 7 CNVT" rather than into Magic Wand. Copy them into the Magic Wand file if you want to use them.
  103.  
  104. There is one more thing that is related to but independent of Clipboard Magician that you can do in system 7. Suppose you copy an ICON from ResEdit into the clipboard, then you go to MacWrite to paste it in. MacWrite will not recognize the ICON in the clipboard. With Clipboard Magician, you can convert the ICON into PICT and then paste it into MacWrite. While that works it is still annoying to have to do it. Many people have expressed the wish that this can be built into the system. You can do this to some extent now. If you got Clipboard Magician from the Developer CD, you should try to get the file "AEMGenSysHandlerLoader" from Apple Event Tools. The file is a CDEV/INIT so it should be dropped into the system folder. You should run the CDEV to enable the GetScrap trap patch (active one should have • in front of the name.) If you did not get Clipboard Magician from the developer CD, you should already has this file set up correctly. Now you can copy some CNVTs from Magic Wand file. The CNVT you can copy over must satisfy the followings. (1) It must be for converting one data type into another data type, i.e. the name must be of the form XXXX>YYYY. (2) It must not own other resource. (3) It cannot be calling other CNVT. After you copy it over you need to activate it by setting the resource attribute to load it into the system heap (alternatively you may use the CDEV to activate it). After the reboot these CNVTs would become system coercion handler. This means that if you copied the ICON>PICT CNVT, then when you asked for an PICT parameter when there is only an ICON parameter in the Apple Event, it would be converted first. This would not benefit you unless you use Apple Event. However the GetScrap patch does one more thing. When any application try to do a GetScrap call, if the desired data type is not there, an Apple Event coercion would be attempted. When MacWrite is doing a GetScrap asking for PICT, if an ICON is in the Clipboard and you have the ICON>PICT CNVT, then MacWrite would think that there is a PICT in the Clipboard and paste it in. Now MacWrite can transparently understand ICON in the clipboard. Some words of caution: these CNVT would be loaded into system heap and takes up space permanently, and the patch has not been extensively tested.
  105.  
  106.